<html>
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
    <title>surf</title>
  </head>
  <body bgcolor="#FFFFFF">
    <center>Scilab Function</center>
    <div align="right">Last update : 31/03/2005</div>
    <p>
      <b>surf</b> - 3D surface plot</p>
    <h3>
      <font color="blue">Calling Sequence</font>
    </h3>
    <dl>
      <dd>
        <tt>surf(Z,&lt;GlobalProperty&gt;)</tt>
      </dd>
      <dd>
        <tt>surf(Z,color,&lt;GlobalProperty&gt;)</tt>
      </dd>
      <dd>
        <tt>surf(X,Y,Z,&lt;color&gt;,&lt;GlobalProperty&gt;)</tt>
      </dd>
      <dd>
        <tt>surf(&lt;axes_handle&gt;,...)</tt>
      </dd>
    </dl>
    <h3>
      <font color="blue">Parameters</font>
    </h3>
    <ul>
      <li>
        <tt>
          <b>Z</b>
        </tt>: a real matrix defining the surface height. It can not be
          omitted. The Z data is a<tt>
          <b> m</b>
        </tt>x<tt>
          <b>n</b>
        </tt> matrix.</li>
      <li>
        <tt>
          <b>X,Y</b>
        </tt>: two real matrices or vectors: always set together, these data
          defines a new standard grid. This new <tt>
          <b>X</b>
        </tt> and
          <tt>
          <b>Y</b>
        </tt> components of the grid must match <tt>
          <b>Z</b>
        </tt>
          dimensions (see description below).</li>
      <li>
        <tt>
          <b>color</b>
        </tt>: an optional real matrix defining a color value for each
          <tt>
          <b>(X(j),Y(i))</b>
        </tt> point of the grid (see description
          below).</li>
      <li>
        <tt>
          <b>&lt;GlobalProperty&gt;</b>
        </tt>: This optional argument represents a sequence of couple
          statements <tt>
          <b>{PropertyName,PropertyValue}</b>
        </tt> that defines
          global objects' properties applied to all the curves created by this
          plot. For a complete view of the available properties (see
          <a href="GlobalProperty.htm">
          <tt>
            <b>GlobalProperty</b>
          </tt>
        </a>).</li>
      <li>
        <tt>
          <b>&lt;axes_handle&gt;</b>
        </tt>: This optional argument forces the plot to appear inside the
          selected axes given by <tt>
          <b>axes_handle</b>
        </tt> rather than the
          current axes (see <a href="gca.htm">
          <tt>
            <b>gca</b>
          </tt>
        </a>).</li>
    </ul>
    <h3>
      <font color="blue">Description</font>
    </h3>
    <p>
      <tt>
        <b>surf</b>
      </tt> draws a colored parametric surface using a
    rectangular grid defined by <tt>
        <b>X</b>
      </tt> and <tt>
        <b>Y</b>
      </tt> coordinates
    (if <tt>
        <b>{X,Y}</b>
      </tt> are not specified, this grid is determined using
    the dimensions of the <tt>
        <b>Z</b>
      </tt> matrix) ; at each point of this grid,
    a Z coordinate is given using the <tt>
        <b>Z</b>
      </tt> matrix (only obligatory
    data). <tt>
        <b>surf</b>
      </tt> has been created to better handle Matlab syntax.
    To improve graphical compatibility, Matlab users should use
    <tt>
        <b>surf</b>
      </tt> (rather than <a href="plot3d.htm">
        <tt>
          <b>plot3d</b>
        </tt>
      </a>).</p>
    <p>Data entry specification :</p>
    <p>In this paragraph and to be more clear, we won't mention
    <tt>
        <b>GlobalProperty</b>
      </tt> optional arguments as they do not interfer
    with entry data (except for <tt>
        <b>"Xdata"</b>
      </tt>, <tt>
        <b>"Ydata"</b>
      </tt> and
    <tt>
        <b>"Zdata"</b>
      </tt> property, see <a href="GlobalProperty.htm">
        <tt>
          <b>GlobalProperty</b>
        </tt>
      </a>). It is
    assumed that all those optional arguments could be present too.</p>
    <p>If <tt>
        <b>Z</b>
      </tt> is the only matrix specified, surf(Z) plots the
    matrix <tt>
        <b>Z</b>
      </tt> versus the grid defined by <tt>
        <b>1:size(Z,2)</b>
      </tt>
    along the x axis and <tt>
        <b>1:size(Z,1)</b>
      </tt> along the y axis.</p>
    <p>If a <tt>
        <b>{X,Y,Z}</b>
      </tt> triplet is given, <tt>
        <b>Z</b>
      </tt> must be a
    matrix with size(<tt>
        <b>Z</b>
      </tt>)= [<tt>
        <b>m</b>
      </tt>x<tt>
        <b>n</b>
      </tt>],
    <tt>
        <b>X</b>
      </tt> or <tt>
        <b>Y</b>
      </tt> can be :</p>
    <dl>
      <dd>
        <b></b>
        <p>a) a vector : if <tt>
            <b>X</b>
          </tt> is a vector,
        length(<tt>
            <b>X</b>
          </tt>)=<tt>
            <b>n</b>
          </tt>. Respectively, if <tt>
            <b>Y</b>
          </tt>
        is a vector, length(<tt>
            <b>Y</b>
          </tt>)=<tt>
            <b>m</b>
          </tt>.</p>
        <p>b) a matrix : in this case, size(<tt>
            <b>X</b>
          </tt>) (or
        size(<tt>
            <b>Y</b>
          </tt>)) must equal size(<tt>
            <b>Z</b>
          </tt>).</p>
      </dd>
    </dl>
    <p>Color entry specification :</p>
    <p>As stated before, the surface is created over a rectangular grid
    support. Let consider two independant variables <tt>
        <b>i</b>
      </tt> and
    <tt>
        <b>j</b>
      </tt> such as :</p>
    <p><IMG ALIGN="CENTERED" src="../../images/graphics/surf_01.gif"></p>
    <dl>
      <dd>
        <b></b>
      </dd>
    </dl>
    <p>This imaginary rectangular grid is used to build the real surface
    support onto the <tt>
        <b>XY</b>
      </tt> plane. Indeed,
    <tt>
        <b>X</b>
      </tt>,<tt>
        <b>Y</b>
      </tt> and <tt>
        <b>Z</b>
      </tt> data have the same size
    (even if <tt>
        <b>X</b>
      </tt> or <tt>
        <b>Y</b>
      </tt> is vector, see below) and can be
    considered as 3 functions <tt>
        <b>x(i,j)</b>
      </tt>, <tt>
        <b>y(i,j)</b>
      </tt> and
    <tt>
        <b>z(i,j)</b>
      </tt> specifying the desired surface. If <tt>
        <b>X</b>
      </tt> or
    <tt>
        <b>Y</b>
      </tt> are vectors, they are internally treated to produce good
    matrices matching the <tt>
        <b>Z</b>
      </tt> matrix dimension (and the grid is
    forcibly a rectangular region).</p>
    <p>Considering the 3 functions <tt>
        <b>x(i,j)</b>
      </tt>, <tt>
        <b>y(i,j)</b>
      </tt>
    and <tt>
        <b>z(i,j)</b>
      </tt>, the portion of surface defining between two
    consecutive <tt>
        <b>i</b>
      </tt> and <tt>
        <b>j</b>
      </tt> is called a patch.</p>
    <p>By default, when no color matrix is added to a surf call, the color
    parameter is linked to the <tt>
        <b>Z</b>
      </tt> data. When a <tt>
        <b>color</b>
      </tt>
    matrix is given, it can be applied to the patch in two different ways : at
    the vertices or at the center of each patch.</p>
    <p>That is why, if <tt>
        <b>Z</b>
      </tt> is a [<tt>
        <b>m</b>
      </tt>x<tt>
        <b>n</b>
      </tt>]
    matrix, the <tt>
        <b>C color</b>
      </tt> matrix dimension can be
    [<tt>
        <b>m</b>
      </tt>x<tt>
        <b>n</b>
      </tt>] (one color defined per vertex) or
    [<tt>
        <b>m-1</b>
      </tt>x<tt>
        <b>n-1</b>
      </tt>] (one color per patch).</p>
    <p>Color representation also varies when specifying some
    GlobalPropery:</p>
    <p>The <tt>
        <b>FaceColor</b>
      </tt> property sets the shading mode : it can
    be<tt>
        <b> 'interp'</b>
      </tt> or <tt>
        <b>'flat'</b>
      </tt> (default mode). When
    <tt>
        <b>'interp'</b>
      </tt> is selected, we perform a bilinear color
    interpolation onto the patch. If size(<tt>
        <b>C</b>
      </tt>) equals
    size(<tt>
        <b>Z</b>
      </tt>)-1 (i.e. we provided only one color per patch) then
    the color of the vertices defining the patch is set to the given color of
    the patch.</p>
    <p>When <tt>
        <b>'flat'</b>
      </tt> (default mode) is enabled we use a color
    faceted representation (one color per patch). If size(<tt>
        <b>C</b>
      </tt>)
    equals size(<tt>
        <b>Z</b>
      </tt>) (i.e. we provided only one color per
    vertices), the last row and column of <tt>
        <b>C</b>
      </tt> are ignored.</p>
    <p></p>
    <p>The <tt>
        <b>GlobalProperty</b>
      </tt> arguments sould be used to customize
    the surface. Here is a brief description on how it works:</p>
    <dl>
      <dd>
        <b></b>
      </dd>
    </dl>
    <dl>
      <dd>
        <b>GlobalProperty</b>: This option may be used to specify how all the surfaces are
        drawn. It must always be a couple statement constituted of a string
        defining the <tt>
          <b>PropertyName</b>
        </tt>, and its associated value
        <tt>
          <b>PropertyValue</b>
        </tt> (which can be a string or an integer or...
        as well depending on the type of the <tt>
          <b>PropertyName</b>
        </tt>). Note
        that you can set multiple properties : the face &amp; edge color,
        color data, color data mapping, marker color (foreground and
        background), the visibility, clipping and thickness of the edges of
        the surface... (see <a href="GlobalProperty.htm">
          <tt>
            <b>GlobalProperty</b>
          </tt>
        </a> )<p>Note that all these properties can be (re-)set throught the surface
        entity properties (see <a href="surface_properties.htm">
            <tt>
              <b>surface_properties</b>
            </tt>
          </a>).</p>
      </dd>
    </dl>
    <h3>
      <font color="blue">Remarks</font>
    </h3>
    <dl>
      <p>By default, successive surface plots are superposed. To clear the
    previous plot, use <tt>
          <b>clf()</b>
        </tt>. To enable <tt>
          <b>auto_clear</b>
        </tt>
    mode as the default mode, edit your default axes doing:</p>
      <p>da=gda();</p>
      <p>da.auto_clear = 'on'</p>
      <p>Enter the command <tt>
          <b>surf</b>
        </tt> to see a demo.</p>
    </dl>
    <h3>
      <font color="blue">Examples</font>
    </h3>
    <pre>
// Z initialisation 

Z= [   0.0001    0.0013    0.0053   -0.0299   -0.1809   -0.2465   -0.1100   -0.0168   -0.0008   -0.0000
    0.0005    0.0089    0.0259   -0.3673   -1.8670   -2.4736   -1.0866   -0.1602   -0.0067    0.0000
    0.0004    0.0214    0.1739   -0.3147   -4.0919   -6.4101   -2.7589   -0.2779    0.0131    0.0020
   -0.0088   -0.0871    0.0364    1.8559    1.4995   -2.2171   -0.2729    0.8368    0.2016    0.0130
   -0.0308   -0.4313   -1.7334   -0.1148    3.0731    0.4444    2.6145    2.4410    0.4877    0.0301
   -0.0336   -0.4990   -2.3552   -2.1722    0.8856   -0.0531    2.6416    2.4064    0.4771    0.0294
   -0.0137   -0.1967   -0.8083    0.2289    3.3983    3.1955    2.4338    1.2129    0.2108    0.0125
   -0.0014   -0.0017    0.3189    2.7414    7.1622    7.1361    3.1242    0.6633    0.0674    0.0030
    0.0002    0.0104    0.1733    1.0852    2.6741    2.6725    1.1119    0.1973    0.0152    0.0005
    0.0000    0.0012    0.0183    0.1099    0.2684    0.2683    0.1107    0.0190    0.0014    0.0000];

//simple surface
surf(Z); // Note that X and Y are determined by Z dimensions

//same surface with red face color and blue edges
scf(2); // new figure number 2
surf(Z,'facecol','red','edgecol','blu")

// X and Y initialisation
// NB: here, X has the same lines and Y the same columns
X = [ -3.0000   -2.3333   -1.6667   -1.0000   -0.3333    0.3333    1.0000    1.6667    2.3333    3.0000
   -3.0000   -2.3333   -1.6667   -1.0000   -0.3333    0.3333    1.0000    1.6667    2.3333    3.0000
   -3.0000   -2.3333   -1.6667   -1.0000   -0.3333    0.3333    1.0000    1.6667    2.3333    3.0000
   -3.0000   -2.3333   -1.6667   -1.0000   -0.3333    0.3333    1.0000    1.6667    2.3333    3.0000
   -3.0000   -2.3333   -1.6667   -1.0000   -0.3333    0.3333    1.0000    1.6667    2.3333    3.0000
   -3.0000   -2.3333   -1.6667   -1.0000   -0.3333    0.3333    1.0000    1.6667    2.3333    3.0000
   -3.0000   -2.3333   -1.6667   -1.0000   -0.3333    0.3333    1.0000    1.6667    2.3333    3.0000
   -3.0000   -2.3333   -1.6667   -1.0000   -0.3333    0.3333    1.0000    1.6667    2.3333    3.0000
   -3.0000   -2.3333   -1.6667   -1.0000   -0.3333    0.3333    1.0000    1.6667    2.3333    3.0000
   -3.0000   -2.3333   -1.6667   -1.0000   -0.3333    0.3333    1.0000    1.6667    2.3333    3.0000];

Y= [   -3.0000   -3.0000   -3.0000   -3.0000   -3.0000   -3.0000   -3.0000   -3.0000   -3.0000   -3.0000
   -2.3333   -2.3333   -2.3333   -2.3333   -2.3333   -2.3333   -2.3333   -2.3333   -2.3333   -2.3333
   -1.6667   -1.6667   -1.6667   -1.6667   -1.6667   -1.6667   -1.6667   -1.6667   -1.6667   -1.6667
   -1.0000   -1.0000   -1.0000   -1.0000   -1.0000   -1.0000   -1.0000   -1.0000   -1.0000   -1.0000
   -0.3333   -0.3333   -0.3333   -0.3333   -0.3333   -0.3333   -0.3333   -0.3333   -0.3333   -0.3333
    0.3333    0.3333    0.3333    0.3333    0.3333    0.3333    0.3333    0.3333    0.3333    0.3333
    1.0000    1.0000    1.0000    1.0000    1.0000    1.0000    1.0000    1.0000    1.0000    1.0000
    1.6667    1.6667    1.6667    1.6667    1.6667    1.6667    1.6667    1.6667    1.6667    1.6667
    2.3333    2.3333    2.3333    2.3333    2.3333    2.3333    2.3333    2.3333    2.3333    2.3333
    3.0000    3.0000    3.0000    3.0000    3.0000    3.0000    3.0000    3.0000    3.0000    3.0000];

// example 1
scf(3)
surf(X,Y,Z)

//example 2
// As you can see, the grid is not necessary rectangular
scf(4)
X(1,4) = -1.5;
Y(1,4) = -3.5;
Z(1,4) = -2;
surf(X,Y,Z)

// example 3
// X and Y are vectors =&gt; same behavior as sample 1
// With vectors, the grid is inevitably rectangular
scf(5)// new figure number 5
X=[ -3.0000   -2.3333   -1.6667   -1.0000   -0.3333    0.3333    1.0000    1.6667    2.3333    3.0000];
Y=X;
surf(X,Y,Z)


//LineSpec and GlobalProperty examples:
xdel(winsid()) // destroy all existing figures
surf(Z,Z+5) // color array specified
e=gce();
e.cdata_mapping='direct' // default is 'scaled' relative to the colormap
e.color_flag=3; // interpolated shading mode. The default is 4 ('flat' mode) for surf

scf(2)
surf(X,Y,Z,'colorda',ones(10,10),'edgeco','cya','marker','penta','markersiz',20,'markeredg','yel','ydata',56:65)

scf(3)
surf(Z,'cdatamapping','direct')
scf(4)
surf(Z,'facecol','interp') // interpolated shading mode (color_flag == 3)

scf(10)
axfig10=gca();
scf(11);
surf(axfig10,Z,'ydat',[100:109],'marker','d','markerfac','green','markeredg','yel') // draw onto the axe of figure 10

xdel(winsid())

 
</pre>
    <h3>
      <font color="blue">See Also</font>
    </h3>
    <p>
      <a href="plot2d.htm">
        <tt>
          <b>plot2d</b>
        </tt>
      </a>,&nbsp;&nbsp;<a href="clf.htm">
        <tt>
          <b>clf</b>
        </tt>
      </a>,&nbsp;&nbsp;<a href="xdel.htm">
        <tt>
          <b>xdel</b>
        </tt>
      </a>,&nbsp;&nbsp;<a href="delete.htm">
        <tt>
          <b>delete</b>
        </tt>
      </a>,&nbsp;&nbsp;<a href="LineSpec.htm">
        <tt>
          <b>LineSpec</b>
        </tt>
      </a>,&nbsp;&nbsp;<a href="GlobalProperty.htm">
        <tt>
          <b>GlobalProperty</b>
        </tt>
      </a>,&nbsp;&nbsp;</p>
    <h3>
      <font color="blue">Author</font>
    </h3>
    <p>F.Leray</p>
  </body>
</html>
